lilconfig

What is lilconfig?

The lilconfig npm package is a lightweight utility for loading configuration files for Node.js projects. It allows developers to search for and read configuration files in various formats from the file system, providing a simple API to work with project configurations.

What are lilconfig's main functionalities?

Searching for configuration files

This feature allows you to search for configuration files related to 'myapp' in the project directory and its parent directories. The search method returns a promise that resolves with the result object containing the file path and its contents if found.

const lilconfig = require('lilconfig');
lilconfig('myapp').search().then(result => {
  console.log(result);
});

Loading configuration from a specific file

This feature allows you to load configuration from a specific file. The load method returns a promise that resolves with the result object containing the file path and its parsed contents.

const lilconfig = require('lilconfig');
lilconfig('myapp').load('path/to/config.json').then(result => {
  console.log(result);
});

Custom loaders for different file formats

This feature allows you to define custom loaders for different file formats. In this example, a custom loader for YAML files is provided using the 'yaml' npm package. The search method will use this loader when a '.yaml' file is encountered.

const lilconfig = require('lilconfig');
const yaml = require('yaml');
const loaders = {
  '.yaml': async filepath => {
    const content = await fs.promises.readFile(filepath, 'utf8');
    return yaml.parse(content);
  }
};
lilconfig('myapp', { loaders }).search().then(result => {
  console.log(result);
});

Other packages similar to lilconfig

cosmiconfig

Cosmiconfig is a similar package that searches for and loads configuration files. It supports various file formats and has a larger feature set, including caching and transforming configurations. It is more widely used than lilconfig but is also more complex and heavier.

rc

The 'rc' package is another alternative that loads configuration from multiple sources, including command-line arguments, environment variables, and configuration files. It is less focused on file discovery and more on aggregating configuration from different sources.

config

The 'config' package is designed for managing configurations across different deployment environments. It is more opinionated and structured than lilconfig, with a predefined way of organizing configuration files based on the deployment environment.

README

Lilconfig ⚙️

A zero-dependency alternative to cosmiconfig with the same API.

Installation

npm install lilconfig

Usage

import {lilconfig, lilconfigSync} from 'lilconfig';

// all keys are optional
const options = {
    stopDir: '/Users/you/some/dir',
    searchPlaces: ['package.json', 'myapp.conf.js'],
    ignoreEmptySearchPlaces: false
}

lilconfig(
    'myapp',
    options // optional
).search() // Promise<LilconfigResult>

lilconfigSync(
    'myapp',
    options // optional
).load(pathToConfig) // LilconfigResult

/**
 * LilconfigResult
 * {
 *   config: any; // your config
 *   filepath: string;
 * }
 */

Difference to cosmiconfig

Lilconfig does not intend to be 100% compatible with cosmiconfig but tries to mimic it where possible. The key differences are:

• no support for yaml files out of the box(lilconfig attempts to parse files with no extension as JSON instead of YAML). You can still add the support for YAML files by providing a loader, see an example below.
• no cache

Options difference between the two.

cosmiconfig option	lilconfig
cache	❌
loaders	✅
ignoreEmptySearchPlaces	✅
packageProp	✅
searchPlaces	✅
stopDir	✅
transform	✅

Loaders examples

Yaml loader

If you need the YAML support you can provide your own loader

import {lilconfig} from 'lilconfig';
import yaml from 'yaml';

function loadYaml(filepath, content) {
    return yaml.parse(content);
}

const options = {
    loaders: {
        '.yaml': loadYaml,
        '.yml': loadYaml,
        // loader for files with no extension
        noExt: loadYaml
    }
};

lilconfig('myapp', options)
    .search()
    .then(result => {
        result // {config, filepath}
    });

ESM loader

Lilconfig v2 does not support ESM modules out of the box. However, you can support it with a custom a loader. Note that this will only work with the async lilconfig function and won't work with the sync lilconfigSync.

import {lilconfig} from 'lilconfig';

const loadEsm = filepath => import(filepath);

lilconfig('myapp', {
    loaders: {
        '.js': loadEsm,
        '.mjs': loadEsm,
    }
})
    .search()
    .then(result => {
        result // {config, filepath}

        result.config.default // if config uses `export default`
    });

Version correlation

• lilconig v1 → cosmiconfig v6
• lilconig v2 → cosmiconfig v7